"""
mc.test 测试工具包类型存根

提供 mc::test 命名空间中的测试基类和工具，用于 MCPy 项目中编写基于 libmcpp 的单元测试。

@mcpy_headers: <test_utilities/test_base.h>
@mcpy_module: mc.test
"""

from typing import Any, TYPE_CHECKING


class TestBase:
    """
    测试基类，提供通用的测试功能
    对应 C++ 中的 mc::test::TestBase
    """

    @staticmethod
    def SetUpTestSuite() -> None:
        """
        测试套件设置，在所有测试开始前调用一次
        设置默认日志级别为 warn，减少测试输出
        """
        ...

    @staticmethod
    def TearDownTestSuite() -> None:
        """
        测试套件清理，在所有测试结束后调用一次
        恢复默认日志级别
        """
        ...

    def SetUp(self) -> None:
        """
        每个测试用例开始时确保日志级别为 warn
        """
        ...

    def TearDown(self) -> None:
        """
        每个测试用例结束时恢复日志级别为 info
        """
        ...


class TestWithRuntime(TestBase):
    """
    带运行时环境的测试基类
    对应 C++ 中的 mc::test::TestWithRuntime
    """

    @staticmethod
    def get_runtime() -> Any:
        """
        获取运行时上下文
        返回 mc::runtime::runtime_context&
        """
        ...

    @staticmethod
    def reset_runtime() -> None:
        """
        重置运行时上下文
        """
        ...

    @staticmethod
    def SetUpTestSuite() -> None:
        """
        重置运行时上下文
        """
        ...

    @staticmethod
    def TearDownTestSuite() -> None:
        """
        重置运行时上下文
        """
        ...


class TestWithDbusDaemon(TestWithRuntime):
    """
    带 DBus 守护进程的测试基类
    对应 C++ 中的 mc::test::TestWithDbusDaemon
    """

    @staticmethod
    def get_dbus_daemon() -> Any:
        """
        获取 DBus 守护进程管理器
        返回 dbus_daemon_manager&
        """
        ...

    @staticmethod
    def SetUpTestSuite() -> None:
        """
        启动 DBus 守护进程
        """
        ...

    @staticmethod
    def TearDownTestSuite() -> None:
        """
        停止 DBus 守护进程
        """
        ...


class TestWithApplication(TestWithDbusDaemon):
    """
    带应用程序的测试基类
    对应 C++ 中的 mc::test::TestWithApplication
    """

    @staticmethod
    def SetUpTestSuite() -> None:
        """
        启动应用程序
        """
        ...

    @staticmethod
    def TearDownTestSuite() -> None:
        """
        停止应用程序并重置
        """
        ...


class TestWithEngine(TestWithApplication):
    """
    带引擎的测试基类
    对应 C++ 中的 mc::test::TestWithEngine
    """

    @staticmethod
    def get_engine() -> Any:
        """
        获取引擎实例
        返回 mc::engine::engine&
        """
        ...

    @staticmethod
    def SetUpTestSuite() -> None:
        """
        设置引擎环境
        """
        ...

    @staticmethod
    def TearDownTestSuite() -> None:
        """
        重置引擎并清理
        """
        ...
